home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / privacy.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  6.4 KB  |  194 lines
  1. /**
  2.  * @file privacy.h Privacy API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_PRIVACY_H_
  26. #define _PURPLE_PRIVACY_H_
  27.  
  28. #include "account.h"
  29.  
  30. /**
  31.  * Privacy data types.
  32.  */
  33. typedef enum _PurplePrivacyType
  34. {
  35.     PURPLE_PRIVACY_ALLOW_ALL = 1,
  36.     PURPLE_PRIVACY_DENY_ALL,
  37.     PURPLE_PRIVACY_ALLOW_USERS,
  38.     PURPLE_PRIVACY_DENY_USERS,
  39.     PURPLE_PRIVACY_ALLOW_BUDDYLIST
  40. } PurplePrivacyType;
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. /**
  47.  * Privacy core/UI operations.
  48.  */
  49. typedef struct
  50. {
  51.     void (*permit_added)(PurpleAccount *account, const char *name);
  52.     void (*permit_removed)(PurpleAccount *account, const char *name);
  53.     void (*deny_added)(PurpleAccount *account, const char *name);
  54.     void (*deny_removed)(PurpleAccount *account, const char *name);
  55.  
  56.     void (*_purple_reserved1)(void);
  57.     void (*_purple_reserved2)(void);
  58.     void (*_purple_reserved3)(void);
  59.     void (*_purple_reserved4)(void);
  60. } PurplePrivacyUiOps;
  61.  
  62. /**
  63.  * Adds a user to the account's permit list.
  64.  *
  65.  * @param account    The account.
  66.  * @param name       The name of the user to add to the list.
  67.  * @param local_only If TRUE, only the local list is updated, and not
  68.  *                   the server.
  69.  *
  70.  * @return TRUE if the user was added successfully, or @c FALSE otherwise.
  71.  */
  72. gboolean purple_privacy_permit_add(PurpleAccount *account, const char *name,
  73.                                  gboolean local_only);
  74.  
  75. /**
  76.  * Removes a user from the account's permit list.
  77.  *
  78.  * @param account    The account.
  79.  * @param name       The name of the user to add to the list.
  80.  * @param local_only If TRUE, only the local list is updated, and not
  81.  *                   the server.
  82.  *
  83.  * @return TRUE if the user was removed successfully, or @c FALSE otherwise.
  84.  */
  85. gboolean purple_privacy_permit_remove(PurpleAccount *account, const char *name,
  86.                                     gboolean local_only);
  87.  
  88. /**
  89.  * Adds a user to the account's deny list.
  90.  *
  91.  * @param account    The account.
  92.  * @param name       The name of the user to add to the list.
  93.  * @param local_only If TRUE, only the local list is updated, and not
  94.  *                   the server.
  95.  *
  96.  * @return TRUE if the user was added successfully, or @c FALSE otherwise.
  97.  */
  98. gboolean purple_privacy_deny_add(PurpleAccount *account, const char *name,
  99.                                gboolean local_only);
  100.  
  101. /**
  102.  * Removes a user from the account's deny list.
  103.  *
  104.  * @param account    The account.
  105.  * @param name       The name of the user to add to the list.
  106.  * @param local_only If TRUE, only the local list is updated, and not
  107.  *                   the server.
  108.  *
  109.  * @return TRUE if the user was removed successfully, or @c FALSE otherwise.
  110.  */
  111. gboolean purple_privacy_deny_remove(PurpleAccount *account, const char *name,
  112.                                   gboolean local_only);
  113.  
  114. /**
  115.  * Allow a user to send messages. If current privacy setting for the account is:
  116.  *        PURPLE_PRIVACY_ALLOW_USERS:    The user is added to the allow-list.
  117.  *        PURPLE_PRIVACY_DENY_USERS    :    The user is removed from the deny-list.
  118.  *        PURPLE_PRIVACY_ALLOW_ALL    :    No changes made.
  119.  *        PURPLE_PRIVACY_DENY_ALL    :    The privacy setting is changed to
  120.  *                                    PURPLE_PRIVACY_ALLOW_USERS and the user
  121.  *                                    is added to the allow-list.
  122.  *        PURPLE_PRIVACY_ALLOW_BUDDYLIST: No changes made if the user is already in
  123.  *                                    the buddy-list. Otherwise the setting is
  124.  *                                    changed to PURPLE_PRIVACY_ALLOW_USERS, all the
  125.  *                                    buddies are added to the allow-list, and the
  126.  *                                    user is also added to the allow-list.
  127.  * 
  128.  * @param account    The account.
  129.  * @param who        The name of the user.
  130.  * @param local        Whether the change is local-only.
  131.  * @param restore    Should the previous allow/deny list be restored if the
  132.  *                    privacy setting is changed.
  133.  */
  134. void purple_privacy_allow(PurpleAccount *account, const char *who, gboolean local,
  135.                         gboolean restore);
  136.  
  137. /**
  138.  * Block messages from a user. If current privacy setting for the account is:
  139.  *        PURPLE_PRIVACY_ALLOW_USERS:    The user is removed from the allow-list.
  140.  *        PURPLE_PRIVACY_DENY_USERS    :    The user is added to the deny-list.
  141.  *        PURPLE_PRIVACY_DENY_ALL    :    No changes made.
  142.  *        PURPLE_PRIVACY_ALLOW_ALL    :    The privacy setting is changed to
  143.  *                                    PURPLE_PRIVACY_DENY_USERS and the user is
  144.  *                                    added to the deny-list.
  145.  *        PURPLE_PRIVACY_ALLOW_BUDDYLIST: If the user is not in the buddy-list,
  146.  *                                    then no changes made. Otherwise, the setting
  147.  *                                    is changed to PURPLE_PRIVACY_ALLOW_USERS, all
  148.  *                                    the buddies are added to the allow-list, and
  149.  *                                    this user is removed from the list.
  150.  *
  151.  * @param account    The account.
  152.  * @param who        The name of the user.
  153.  * @param local        Whether the change is local-only.
  154.  * @param restore    Should the previous allow/deny list be restored if the
  155.  *                    privacy setting is changed.
  156.  */
  157. void purple_privacy_deny(PurpleAccount *account, const char *who, gboolean local,
  158.                         gboolean restore);
  159.  
  160. /**
  161.  * Check the privacy-setting for a user.
  162.  *
  163.  * @param account    The account.
  164.  * @param who        The name of the user.
  165.  *
  166.  * @return @c FALSE if the specified account's privacy settings block the user or @c TRUE otherwise. The meaning of "block" is protocol-dependent and generally relates to status and/or sending of messages.
  167.  */
  168. gboolean purple_privacy_check(PurpleAccount *account, const char *who);
  169.  
  170. /**
  171.  * Sets the UI operations structure for the privacy subsystem.
  172.  *
  173.  * @param ops The UI operations structure.
  174.  */
  175. void purple_privacy_set_ui_ops(PurplePrivacyUiOps *ops);
  176.  
  177. /**
  178.  * Returns the UI operations structure for the privacy subsystem.
  179.  *
  180.  * @return The UI operations structure.
  181.  */
  182. PurplePrivacyUiOps *purple_privacy_get_ui_ops(void);
  183.  
  184. /**
  185.  * Initializes the privacy subsystem.
  186.  */
  187. void purple_privacy_init(void);
  188.  
  189. #ifdef __cplusplus
  190. }
  191. #endif
  192.  
  193. #endif /* _PURPLE_PRIVACY_H_ */
  194.